/*
 * Code for blog.techhead.biz
 * Distributed under BSD-style license
 */
package biz.techhead.funcy;

/**
 * A Range here is a finite or infinite set that can be stepped through in a
 * predictable way.  The direction of the iteration and the inclusion or
 * exclusion of endpoints is implementation specific.
 *
 * <p>All {@code Range} implementations should be Thread safe as should all
 * {@code Iterable} instances returned by the {@link #by(Step)} method.
 * However, each Iterable's {@code Iterator} is intended for use by only a
 * single Thread.
 *
 * 
 * @param <T> The element type of the Range
 * @see Ranges Ranges
 *
 * @author Jonathan Hawkes <jhawkes at techhead.biz>
 */
public interface Range<T> {

    /**
     * Returns {@code true} if the given item falls within this Range.
     */
    boolean contains(T item);

    /**
     * Returns an {@code Iterable} which will iterate over this Range using the
     * given {@link Step}.  Which direction (up or down) this Iterable
     * will move is implementation specific.
     */
    Iterable<T> by(Step<T> step);
}
